<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
    <link rel="StyleSheet" href="css/style.css" type="text/css">
    <meta content="text/html; charset=ISO-8859-1"
          http-equiv="content-type">
    <meta name="verify-v1"
          content="sRQSq4VA5FRMhwzFB4U3I9AtgLMtIWTdpVVO6jg1az4=">
    <title>AtomServer Categories</title>
    <script type="text/javascript">
        var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
        document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
    </script>
    <script type="text/javascript">
        var pageTracker = _gat._getTracker("UA-4603527-2");
        pageTracker._initData();
        pageTracker._trackPageview();
    </script>
</head>
<body class="maincontent">
<h1><img style="width: 75px; height: 75px;" src="images/atom-logo.gif"
         alt="logo">&nbsp;
    <span style="font-weight: bold;"></span>AtomServer, Category Details </h1>

<div class="content"><span style="font-style: italic;">Chris Berry,
Bryon Jacob. Updated 08/15/08 <br>
</span><br>
This
document describes some specific details about dealing with AtomServer
Categories
including information about creating Categories and searching Feeds for
Entries based on their Categories. <br>
<br>
For a further, detailed description of the actual protocol, either<br>
<ul>
    <li>See <a href="http://www.atomenabled.org/developers/syndication/">the
        Atom Publishing Protocol Reference</a> for further information about
        the
        elements of the feed itself. Note that we do not exhaustingly document
        this
        information ourselves,&nbsp; because we are using Atom entirely as
        dictated
        by the standard.
    </li>
    <li>See <a href="protocol_basics.html">the AtomServer Protocol
        Basics document </a>for general information about communicating with
        the AtomServer service.<br>
    </li>
</ul>
This document does <span style="font-weight: bold;">not</span> explain
the underlying concepts behind AtomServer; REST, Atom, and OpenSearch.
That
information can be found in <a href="intro.html">the AtomServer
    General Introduction document</a>. <span style="font-style: italic;">It
is highly recommended that you read this document first</span>.<br>
<br>
Nor does this document explain the basics of XML,
namespaces, syndicated feeds, and the <span
        style="font-family: monospace;">GET, POST, PUT</span>, and <span
        style="font-family: monospace;">DELETE</span>
requests in HTTP, as well as HTTP's concept of a "resource." For more
information about those things, see the <a href="#resources">Additional
    resources </a>section of
this document.<br>

<h2>Contents</h2>
<ul>
    <li><a href="#intro">General Information</a></li>
    <li><a href="#manage">Managing Categories</a></li>
    <ul>
        <li><a href="#PUT">Creating or Modifying the Categories for a
            specific Entry</a><br>
        </li>
        <li><a href="#GET">Requesting the Categories for a specific Entry</a></li>
        <li><a href="#DELETE">Deleting the Categories for a specific Entry</a></li>
        <li><a href="#service">Requesting all of the Categories associated
            with a Workspace or
            Collection</a></li>
        <li><a href="#single">Modifying a Single Category for a specific Entry</a></li>
    </ul>
    <li><a href="#Queries">Category Queries</a></li>
    <ul>
        <li><a href="#ComplexQueries">Complex Category Queries</a><br>
        </li>
    </ul>
    <li><a href="#resources">Additional Resources</a><br>
    </li>
</ul>
<hr style="width: 100%; height: 2px;">
<h2><a name="intro"></a>General Information<br>
</h2>
Most data requires categorization to make it more manageable,
especially as the data grows in size. Categorization is the
characterization of data into collections based on some common
attribute. And, not surprising, the Atom specification provides a
built-in mechanism for categorization. <br>

<p id="rfc.section.7.p.1">Atom provides the concept of Category
    Documents, which contain lists of categories described using the
    "atom:category" element from the Atom Syndication Format <a
            href="http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#RFC4287"
            title="The Atom Syndication Format">[RFC4287]</a>. Categories can also
    appear in Service Documents, where they describe the categories allowed
    in a Collection (see <a
            href="http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#categories-elem"
            title="The &quot;app:categories&quot; Element">Section&nbsp;8.3.5</a>). <br>
</p>

<p id="rfc.section.7.p.2">Category Documents are identified with the
    "application/atomcat+xml" media type (see <a
            href="http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#iana"
            title="IANA Considerations">Section&nbsp;16</a>). <br>
</p>

<p id="rfc.section.7.p.2">The root of a Category Document is the
    "app:categories" element. An
    app:categories element can contain zero or more "atom:category"
    elements from the Atom namespace. A Category is simply a way to assign
    arbitrary attributes to an Entry. And then using these categories&nbsp;
    the User can then group Entries into arbitrary collections. <br>
</p>

<p><code>&lt;category&gt;</code> has one required attribute, <code>term</code>,
    and two optional attributes, <code>scheme</code> and <code>label</code>.</p>

<p style="margin-left: 40px;"><code style="font-weight: bold;">term</code><span
        style="font-weight: bold;"> </span>identifies the category</p>

<p style="margin-left: 40px;"><code style="font-weight: bold;">scheme</code>
    identifies the categorization scheme via a <abbr
            title="Universal Resource Identifier">URI</abbr>. While scheme is
    optional within the Atom spec, <span style="font-style: italic;">AtomServer
<span style="font-weight: bold;">requires</span> the scheme attribute</span>.
    You can think of schemes as a namespace. Within AtomServer we currently
    do <span style="font-weight: bold;">not</span> accept schemes with "/"
    characters, although this is a valid URI character. You are encouraged
    to create schemes using a "." delimited hierarchy. (e.g
    "urn:foo.widgets.brands")<br>
</p>

<p style="margin-left: 40px;"><code style="font-weight: bold;">label</code>
    provides a human-readable label for display. <span
            style="font-style: italic;">AtomServer does not currently support the
"label" attribute in full</span>.</p>

<h3>Example</h3>

<div id="codebox">
    <pre>    &lt;?xml version="1.0" ?&gt;<br>    &lt;app:categories<br>        xmlns:app="http://www.w3.org/2007/app"<br>        xmlns="http://www.w3.org/2005/Atom"&gt;<br>      &lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>      &lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>    &lt;/app:categories&gt;</pre>
</div>
<p id="rfc.section.7.1.p.2">This Category Document contains
    two categories, with the terms "foo" and "bar".
    None of the categories use the 'label' attribute defined in <a
            href="http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html#RFC4287"
            title="The Atom Syndication Format">[RFC4287]</a>.
    They both use the&nbsp; "urn:foo.widgets" 'scheme' attribute .
    Therefore if the "foo"
    category were to appear in an Atom Entry or Feed Document, it would
    appear as:</p>

<div id="codebox">
    <pre>&lt;category scheme="urn:foo.widgets" term="foo" /&gt;</pre>
</div>
<hr style="width: 100%; height: 2px;">
<h2><a name="manage"></a>Managing Categories </h2>
Managing categories within AtomServer does <span
        style="font-weight: bold;">not
</span>follow the standard Atom technique for managing categories. In
Atom you would create a Category for a given Entry by submitting it
within that Entry
during a PUT or POST. This was determined to be too burdensome for the
Entry publishers, each of which would have to be fully "Category-aware"
and would have to honor optimistic concurrency restrictions.<br>
<br>
Instead, AtomServer has chosen a Separation of Concerns. Within
AtomServer
Categories are a completely separate Resource, maintained in a <span
        style="font-style: italic;">virtual </span>parallel
Workspace. The name for this Workspace is arbitrary - it is assigned
within AtomServer's Spring configuration file. But, by convention, we
are
using a "tags:" prefix for all Category Workspaces. Thus, the
Categories for "widgets" are edited using the "tags:lwidgets"
Workspace. <br>
<br>
Interaction with Category Workspaces follows all the same rules as
interaction with any Workspace, as described in <a
        href="protocol_basics.html">here</a>. Although, for Category
Workspaces one <span style="font-weight: bold;">must</span> follow the
optimistic concurrency restrictions.<br>

<h3><a name="PUT"></a>Creating or Modifying Categories for a specific
    Entry<br>
</h3>
To create or modify the Categories which apply to a given Entry, send a
<span style="font-family: monospace;">PUT</span>
request, and supply a standard Atom Categories document within the
&lt;content&gt; element. Note that there is effectively no difference
between an
Update and an Insert, <span style="font-style: italic;">except</span>
for Updates, where you <span style="font-weight: bold;">must</span>
provide the revision identifier. And because the "Categories Workspace"
is <span style="font-style: italic;">virtual</span>, this revision
number<span style="font-weight: bold;"> must </span>be the one for the
"real" Entry. <br>
<br>
Let's look at an example,&nbsp; imagine that you want to supply
Categories for the Entry
identified as <span style="font-family: monospace;">/widgets/acme/123.xml<span
        style="font-weight: bold;">/2</span></span><span
        style="font-weight: bold;">,</span> so by the rules governing <a
        href="protocol_reference.html#Optimistic_concurrency_versioning">AtomServer
    Optimistic Concurrency</a>, you must submit your Categories request to <span
        style="font-family: monospace;">/tags:widgets/acme/123.xml<span
        style="font-weight: bold;">/3</span></span>. As
you can see, we've created an implicit mapping between the "actual"
Entry ("widgets/acme/123.xml") and the Category Entry
("tags:widgets/acme/123.xml"). <br>
<br>
NOTE: The User must take great care when editing Categories. <span
        style="font-style: italic;">It is the User's responsibility to deal
with all "merge conflicts"</span>. Put simply, when AtomServer receives
a
list of Categories to apply to a given Entry, it will first <span
        style="font-style: italic;">delete all existing Categories</span>,
before inserting the current list of Categories. Thus, the User <span
        style="font-weight: bold;">must</span> make certain that the list of
Categories they are submitting is correct and preserve whatever
necessary Categories they received from a previous GET or PUT. While
the rules of optimistic concurrency apply, you cannot write an Entry
without supplying the correct next revision Id, these rules do not
protect you from negligence. <br>
<br>
NOTE: the XML namespace qualifier ( e.g. <span
        style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"</span>&gt;) is <span
        style="font-weight: bold;">required</span> by the Atompub
specification!<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">PUT
/v1/tags:widgets/acme/123.xml/3</span><br>
        <br>
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atomserver/v1/tags:widgets/acme/123&lt;/id&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories </span><span style="font-weight: bold;">xmlns:app="http://www.w3.org/2007/app"</span></span><span
                style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;&nbsp;
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/app:categories&gt;</span><span
                style="font-family: monospace;"></span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp;&nbsp; &lt;/content&gt; </span><br>
        <span style="font-family: monospace;">&lt;/entry&gt;</span>&nbsp; </div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;?xml version='1.0'
encoding='UTF-8'?&gt;<br>
&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;<br>
&nbsp;&nbsp; &lt;id&gt;/atomserver/v1/tags:widgets/acme/123&lt;/id&gt;<br>
&nbsp;&nbsp; &lt;updated&gt;2007-08-06T22:58:11.030Z&lt;/updated&gt;<br>
&nbsp;&nbsp; &lt;published&gt;2007-08-06T22:58:11.030Z&lt;/published&gt;<br>
&nbsp;&nbsp; &lt;title type="text"&gt;AtomServer Feed
Entry&lt;/title&gt;<br>
&nbsp;&nbsp; &lt;content</span><span style="font-family: monospace;">
type="application/xml" </span><span style="font-family: monospace;">&gt;<br>
</span><span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories xmlns:app="http://www.w3.org/2007/app"</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/app:categories&gt;</span><span
                style="font-family: monospace;"><br style="font-weight: bold;">
&nbsp;&nbsp; &lt;/content&gt;<br>
&nbsp;&nbsp; &lt;author&gt;&lt;name&gt;AtomServer Atom
Service&lt;/name&gt;&lt;/author&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml/3"
rel="edit" /&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml"
rel="self" /&gt;<br>
&lt;/entry&gt;</span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;">
</span><span style="font-family: monospace;"></span><br>
</div>
Note that the client does not need to provide any of the <span
        style="font-family: monospace;">entry</span> elements
when creating an Entry except for <span style="font-family: monospace;">&lt;id&gt;</span>,
which <span style="font-weight: bold;">must</span> be provided.<br>

<h3><a name="GET"></a>Requesting the Categories for a specific entry<br>
</h3>
You don't have to do anything special to request the Categories
associated with a specific, "actual" Entry, because all Categories
associated with that Entry are automatically returned when you request
that Entry <br>
<br>
So, for example, let's assume that you are requesting the <span
        style="font-style: italic;">acme</span> Widget;
123. And let's further assume that we've associated Categories with
this Entry as in <a href="#PUT">the preceding example</a>. <br>
To see it, you would send the following request to the server. Notice
that we are requesting the "actual" Entry, and that the Entry's
Categories are always returned for that request.<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/123.xml</span></div>
</div>
<br>
The server responds with:<span style="font-family: monospace;"></span><span
        style="font-family: monospace;"><br>
</span>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;?xml version='1.0'
encoding='UTF-8'?&gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atom/v1/widgets/acme/123&lt;/id&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;
&lt;updated&gt;2007-06-18T23:29:32.000Z&lt;/updated&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp; &lt;title
type="text"&gt;Acme Widget (123)&lt;/title&gt;<br>
</span><span style="font-family: monospace;">&nbsp;&nbsp; &lt;</span><span
                style="font-family: monospace;">link
xmlns="http://www.w3.org/2005/Atom"
href="/atomserver/v1/widgets/acme/123.xml/4" rel="edit" /&gt;</span><br>
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;<span
                style="font-weight: bold;"> &lt;category scheme="urn:foo.widgets.type"
term="foo" /&gt;</span><br style="font-weight: bold;">
<span style="font-weight: bold;">&nbsp;&nbsp; &lt;category
scheme="urn:foo.widgets.brands" term="bar" /&gt;</span></span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;property
xmlns="http://schemas.atomserver.org/widgets/v1/rev0" systemId="acme"
id="123" inNetwork="false"&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .....<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/property&gt;<br>
&nbsp;&nbsp; &lt;/content&gt; </span><span
                style="font-family: monospace;"><br>
&lt;/entry&gt;</span></div>
    <span style="font-family: monospace;"></span>
</div>
<br>
Note that the Entry contains the two Categories we had assigned to it
previously (i.e. <span style="font-family: monospace;">foo</span>
and <span style="font-family: monospace;">bar</span>).<br>

<h3><a name="DELETE"></a>Deleting the Categories for a specific entry</h3>
To delete the Categories associated with an existing Entry, send a
DELETE request, using the Entry's
<span style="font-family: monospace;">edit</span> URI (as provided by
the server in the previous example).<br>
<br>
If your firewall does not allow DELETE, then do an HTTP POST and set
the method override header as follows:<br>

<div style="margin-left: 40px;">&nbsp;<br>

    <div id="codebox"><span style="font-family: monospace;">X-HTTP-Method-Override:
DELETE</span><br>
    </div>
<span style="font-family: monospace;"><br>
</span></div>
The following example deletes <span style="font-weight: bold;">all</span>
categories associated with the "actual" Entry
widgets/acme/123.xml. Note that, again, we must follow the rules of
AtomServer Optimistic Concirrency.<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">DELETE
</span><span style="font-family: monospace;">/v1/tags:widgets/acme/123.xml/4</span><span
            style="font-family: monospace;"></span><br>
    </div>
    <span style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><span style="font-family: monospace;"></span>&nbsp; </div>
</div>
<br>
If the deletion fails, then the server responds with an error code.<br>

<h3><a name="service"></a>Requesting all Categories associated with a
    Workspace or Collection</h3>
Atom provides a standard way to ask for all Categories associated with
either a Workspace or with a specific Collection within a Workspace.
This is provided within the standard "<span style="font-style: italic;">Service
Document</span>". The Atom Service Document is how a service tells you
what is available. It is the introspection document. Each service
represents one or more <i>workspaces</i>, which represent one or more <i>collections</i>.
The collections contain the individual resources (Entries). <br>
<br>
By definition, a Service Document may contain a "Categories Document"
for each Collection. You can request either all available Workspaces
(by making the GET request to the "base URL" - e.g. "/v1" ) or a
particular Workspace (by making the GET request to the "base Workspace
URL" - e.g. "/v1/widgets").<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">GET
/v1/</span><span style="font-family: monospace;"></span></div>
    <span style="font-family: monospace;"></span><br>
</div>
might return;<br>

<div style="margin-left: 40px;"><span style="font-family: monospace;"></span><br>

    <div id="codebox"><span style="font-family: monospace;">&lt;?xml
version='1.0' encoding='UTF-8'?&gt;</span><br
            style="font-family: monospace;">
<span style="font-family: monospace;">&lt;service
xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;workspace&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;atom:title
type="text"&gt;widgets&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;collection
href="widgets/acme/"&gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;atom:title type="text"&gt;acme&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;accept&gt;application/atom+xml;type=entry&lt;/accept&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;categories&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.bar" term="term1" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term1" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term3" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term2" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;/categories&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;/collection&gt;</span><br style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;/workspace&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;workspace&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;atom:title type="text"&gt;other1&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;/workspace&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;workspace&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;atom:title
type="text"&gt;other2&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;/workspace&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&lt;/service&gt; </span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span>
</div>
<br>
Or you can request a particular Workspace;<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets</span></div>
    <span style="font-family: monospace;"></span><br>
</div>
might return;<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">&lt;?xml
version='1.0' encoding='UTF-8'?&gt;</span><br
            style="font-family: monospace;">
<span style="font-family: monospace;">&lt;service
xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;
&lt;workspace&gt;&lt;atom:title
type="text"&gt;widgets&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;collection
href="widgets/acme/"&gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp; &nbsp;&nbsp;
&lt;atom:title type="text"&gt;acme&lt;/atom:title&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;accept&gt;application/atom+xml;type=entry&lt;/accept&gt;</span><br
                style="font-family: monospace;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;
&nbsp;&nbsp; &lt;categories&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp; &lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.bar" term="term1" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp; &lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term1" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term3" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp; &lt;category xmlns="http://www.w3.org/2005/Atom"
scheme="urn:widgets.foo" term="term2" /&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;/categories&gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;/collection&gt;</span><br style="font-family: monospace;">
        <span style="font-family: monospace;">&nbsp; &lt;/workspace&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;">&lt;/service&gt;</span></div>
    <span style="font-family: monospace;"></span>
</div>
<br>

<h3><a name="single"></a>Modifying a Single Category for a specific Entry<br>
</h3>
With standard Atom Categories document, categories for an entry can be modified as a whole. Instead of
modifying all categories of an entry, a <span style="font-weight: bold;">Single Category</span> document can be used
to modify a single category within the categories. <br>
<br>
A Single Category document is an extension to Atom Categories document with a name-spaced
element <span style="font-weight: bold;">category-op</span>. The element <span style="font-weight: bold;">category-op</span>
specifies the type of operation to perform with the category in the
document. Currently the AtomServer supports "<span style="font-style: italic;">modify</span>" operation which changes
the categories of the entry and allows modification of one category per document.</br>
<br>
To modify a single Category which apply to a given Entry, send a <span style="font-family: monospace;">PUT</span>
request,
and supply a Single Atom Category document within the&lt;content&gt; element.<br>
<br>
A <span style="font-weight: bold;">category</span>
element in the single Category document must specify <span style="font-weight: bold;">modifyType</span> in
addition to the scheme, term, and optional label. <span style="font-weight: bold;">modifyType</span> is a name-spaced
attribute which describes what to do with the category in the document. A category can be inserted or added to existing
categories, it's term value can be updated to a new value, or it can be deleted from existing categories. Corresponding values for
<span style="font-weight: bold;">modifyType</span> are <span style="font-style: italic;">insert,
update,</span> and <span style="font-style: italic;">delete.</span><br>
<br>
For the update operation, an additional name-spaced attribute called <span style="font-weight: bold;">oldTerm</span> must be specified
in the category element.
<span style="font-weight: bold;">oldTerm</span> specifies the existing term of the category with the same scheme. The term of the category
which matches scheme and oldTerm attribute values will be updated to the value of the term attribute. If a category matches the scheme, but not the
oldTerm, AtomServer considers this as an optimistic concurrency error and http status code of 409 (Conflict) is returned.
If there are no categories which matches the scheme, AtomServer will return status code 400 (Bad request).<br>
<br>
Examples of using Single Category document follow.<br>
<h4>1. Insert a new category to entry with Id 12345.</h4>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">PUT
/v1/tags:widgets/acme/12345.xml/1</span><br>
        <br>
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atomserver/v1/tags:widgets/acme/12345&lt;/id&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories </span><span style="font-weight: bold;">xmlns:app="http://www.w3.org/2007/app"</span><span
                style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;&nbsp;
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom"</span><span style="font-weight: bold;"><br style="font-family: monospace; font-weight: bold;">
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        xmlns:catop="http://atomserver.org/namespaces/1.0/category" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
        <span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;catop:category-op type="modify"/&gt;<br>
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="US" catop:modifyType="insert" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/app:categories&gt;</span><span
                style="font-family: monospace; "></span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;font-weight:normal;">&nbsp;&nbsp; &lt;/content&gt; </span><br>
        <span style="font-family: monospace;font-weight:normal;">&lt;/entry&gt;</span>&nbsp; </div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;?xml version='1.0'
encoding='UTF-8'?&gt;<br>
&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;<br>
&nbsp;&nbsp; &lt;id&gt;/atomserver/v1/tags:widgets/acme/12345&lt;/id&gt;<br>
&nbsp;&nbsp; &lt;updated&gt;2010-08-06T22:58:11.030Z&lt;/updated&gt;<br>
&nbsp;&nbsp; &lt;published&gt;2010-08-06T22:58:11.030Z&lt;/published&gt;<br>
&nbsp;&nbsp; &lt;title type="text"&gt;AtomServer Feed
Entry&lt;/title&gt;<br>
&nbsp;&nbsp; &lt;content</span><span style="font-family: monospace;">
type="application/xml" </span><span style="font-family: monospace;">&gt;<br>
</span><span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories xmlns:app="http://www.w3.org/2007/app"</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="US" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/app:categories&gt;</span><span
                style="font-family: monospace;"><br style="font-weight: bold;">
&nbsp;&nbsp; &lt;/content&gt;<br>
&nbsp;&nbsp; &lt;author&gt;&lt;name&gt;AtomServer Atom
Service&lt;/name&gt;&lt;/author&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml/1"
rel="edit" /&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml"
rel="self" /&gt;<br>
&lt;/entry&gt;</span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;">
</span><span style="font-family: monospace;"></span><br>
</div>


<h4>2. a) Update a category with new term to entry with Id 12345 with incorret oldTerm.</h4>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">PUT
/v1/tags:widgets/acme/12345.xml/2</span><br>
        <br>
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atomserver/v1/tags:widgets/acme/12345&lt;/id&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories </span><span style="font-weight: bold;">xmlns:app="http://www.w3.org/2007/app"</span></span><span
                style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;&nbsp;
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom"</span><span style="font-weight: bold;"><br style="font-family: monospace; font-weight: bold;">
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        xmlns:catop="http://atomserver.org/namespaces/1.0/category" &gt;</span>
        <br>
        <span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;catop:category-op type="modify"/&gt;
        <br
                style="font-family: monospace; font-weight: bold;">

<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="Canada" catop:modifyType="update" catop:oldTerm="UK" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/app:categories&gt;</span><span
                style="font-family: monospace;"></span><br
                style="font-family: monospace;font-weight:normal;">
        <span style="font-family: monospace;font-weight:normal;">&nbsp;&nbsp; &lt;/content&gt; </span><br>
        <span style="font-family: monospace;font-weight:normal;">&lt;/entry&gt;</span>&nbsp; </div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">409
Conflict</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;error xmlns="http://incubator.apache.org/abdera"&gt;<br>
&nbsp;&nbsp; &lt;code&gt;409&lt;/code&gt;<br>
&nbsp;&nbsp; &lt;message&gt;Optimisitic Concurrency Error:: /atomserver/v1/tags:widgets/acme/12345.xml/2&lt;/message&gt;<br>
&nbsp;&nbsp; &lt;link xmlns="http://www.w3.org/2005/Atom" href="/atomserver/v1/widgets/acme/12345.xml/2" rel="edit" /&gt;<br>
&lt;/error&gt;</span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;">
</span><span style="font-family: monospace;"></span><br>
</div>



<h4>2. b) Update a category with new term to entry with Id 12345 with correct oldTerm.</h4>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">PUT
/v1/tags:widgets/acme/12345.xml/2</span><br>
        <br>
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atomserver/v1/tags:widgets/acme/12345&lt;/id&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories </span><span style="font-weight: bold;">xmlns:app="http://www.w3.org/2007/app"</span></span><span
                style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;&nbsp;
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom"</span><span style="font-weight: bold;"><br style="font-family: monospace; font-weight: bold;">
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        xmlns:catop="http://atomserver.org/namespaces/1.0/category" &gt;</span>
        <br>
        <span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;catop:category-op type="modify"/&gt;
        <br
                style="font-family: monospace; font-weight: bold;">
        
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="Canada" catop:modifyType="update" catop:oldTerm="US" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/app:categories&gt;</span><span
                style="font-family: monospace;"></span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;font-weight:normal;">&nbsp;&nbsp; &lt;/content&gt; </span><br>
        <span style="font-family: monospace;font-weight:normal;">&lt;/entry&gt;</span>&nbsp; </div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;?xml version='1.0'
encoding='UTF-8'?&gt;<br>
&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;<br>
&nbsp;&nbsp; &lt;id&gt;/atomserver/v1/tags:widgets/acme/123&lt;/id&gt;<br>
&nbsp;&nbsp; &lt;updated&gt;2010-08-06T22:58:11.030Z&lt;/updated&gt;<br>
&nbsp;&nbsp; &lt;published&gt;2010-08-06T22:58:11.030Z&lt;/published&gt;<br>
&nbsp;&nbsp; &lt;title type="text"&gt;AtomServer Feed
Entry&lt;/title&gt;<br>
&nbsp;&nbsp; &lt;content</span><span style="font-family: monospace;">
type="application/xml" </span><span style="font-family: monospace;">&gt;<br>
</span><span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories xmlns:app="http://www.w3.org/2007/app"</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="Canada" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/app:categories&gt;</span><span
                style="font-family: monospace;"><br style="font-weight: bold;">
&nbsp;&nbsp; &lt;/content&gt;<br>
&nbsp;&nbsp; &lt;author&gt;&lt;name&gt;AtomServer Atom
Service&lt;/name&gt;&lt;/author&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml/2"
rel="edit" /&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml"
rel="self" /&gt;<br>
&lt;/entry&gt;</span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;">
</span><span style="font-family: monospace;"></span><br>
</div>


<h4>3. Delete an existing category to entry with Id 12345.</h4>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">PUT
/v1/tags:widgets/acme/12345.xml/3</span><br>
        <br>
<span style="font-family: monospace;">&lt;entry
xmlns="http://www.w3.org/2005/Atom"&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp;
&lt;id&gt;/atomserver/v1/tags:widgets/acme/12345&lt;/id&gt;</span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;"></span><span
                style="font-family: monospace;">&nbsp;&nbsp; &lt;content
type="application/xml" &gt;</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories </span><span style="font-weight: bold;">xmlns:app="http://www.w3.org/2007/app"</span></span><span
                style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;&nbsp;
<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom"</span><span style="font-weight: bold;"><br style="font-family: monospace; font-weight: bold;">
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
        xmlns:catop="http://atomserver.org/namespaces/1.0/category" &gt;</span>
        <br/>
        <span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;catop:category-op type="modify"/&gt;
<br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.location" term="Canada" catop:modifyType="delete" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;/app:categories&gt;</span><span
                style="font-family: monospace;"></span><br
                style="font-family: monospace;">
        <span style="font-family: monospace;font-weight:normal;">&nbsp;&nbsp; &lt;/content&gt; </span><br>
        <span style="font-family: monospace;font-weight:normal;">&lt;/entry&gt;</span>&nbsp; </div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span><span
            style="font-family: monospace;"></span></div>
<br>
The server responds:<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">200
OK</span><br style="font-family: monospace;">
        <br>
<span style="font-family: monospace;">&lt;?xml version='1.0'
encoding='UTF-8'?&gt;<br>
&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;<br>
&nbsp;&nbsp; &lt;id&gt;/atomserver/v1/tags:widgets/acme/123&lt;/id&gt;<br>
&nbsp;&nbsp; &lt;updated&gt;2010-08-06T22:58:11.030Z&lt;/updated&gt;<br>
&nbsp;&nbsp; &lt;published&gt;2010-08-06T22:58:11.030Z&lt;/published&gt;<br>
&nbsp;&nbsp; &lt;title type="text"&gt;AtomServer Feed
Entry&lt;/title&gt;<br>
&nbsp;&nbsp; &lt;content</span><span style="font-family: monospace;">
type="application/xml" </span><span style="font-family: monospace;">&gt;<br>
</span><span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;
&lt;app:categories xmlns:app="http://www.w3.org/2007/app"</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
xmlns="http://www.w3.org/2005/Atom" &gt;</span><br
                style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.type" term="foo" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;category scheme="urn:foo.widgets.brands" term="bar" /&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp; &lt;/app:categories&gt;</span><span
                style="font-family: monospace;"><br style="font-weight: bold;">
&nbsp;&nbsp; &lt;/content&gt;<br>
&nbsp;&nbsp; &lt;author&gt;&lt;name&gt;AtomServer Atom
Service&lt;/name&gt;&lt;/author&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml/3"
rel="edit" /&gt;<br>
&nbsp;&nbsp; &lt;link href="/atomserver/v1/widgets/acme/12345.en.xml"
rel="self" /&gt;<br>
&lt;/entry&gt;</span></div>
    <span style="font-family: monospace;"></span><span
            style="font-family: monospace;">
</span><span style="font-family: monospace;"></span><br>
</div>



<hr style="width: 100%; height: 2px;">
<h2><a name="Queries"></a>Category Queries <br>
</h2>
The usefulness of Categories lies, of course, in the ability to query
for Feeds (i.e. lists of Entries) which have particular Categories
associated with them. Since AtomServer is modeled after GData, we've
adopted a similar scheme for "Category Queries" as that in GData.
Instead of using Query Parameters to specify Category search parameters
(e.g. foo/bar/123?category=foo&amp;category=bar), we've adopted GData's
URL scheme. Although we have <span style="font-weight: bold;">not </span>adopted
GData's scheme verbatim because the GData scheme employs several
Invalid URL characters, which require that the User explicitly encode
them in the URL (e.g. "|" must be encoded as %7C) . So rather than do
that to our Users, and for the sake of readable URLs, we've adopted a
slightly different syntax. <br>
<br>
To retrieve a Feed of Entries that match a particular Category - say
the "bar" Category we <a href="#PUT">implemented earlier</a>, you
would
submit a request like this;<br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/-/(urn:foo.widgets.brands)bar </span></div>
</div>
<br>
where<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span
        style="font-family: monospace;">/-/&nbsp;</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; is the URL delimiter which
indicates that a Category query follows.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span
        style="font-family: monospace;">(urn:foo.widgets.brands)&nbsp;</span>
is the Category scheme.&nbsp; schemes are delimited by parenthesis; <span
        style="font-family: monospace;">(</span> and <span
        style="font-family: monospace;">).</span>&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span
        style="font-family: monospace;">bar </span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
is the Category term<br>
<br>
You can "chain" together a series of "ANDs" by simply requesting a
series of Categories. For example; <br>

<div style="margin-left: 40px;"><br>

    <div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/-/(urn:foo.widgets.brands)bar/(urn:foo.widgets.type)foo</span>
    </div>
    <span style="font-family: monospace;"></span><br>
</div>
is the equivalent of asking "give me a Feed of all widgets that have
Category {urn:widgets.brands, bar} AND {urn:widgets.type, foo}"<br>
<br>

<h2><a name="ComplexQueries"></a>Complex Category Queries<br>
</h2>
Category queries also support arbitrarily complex boolean expressions
using AND and OR operators explicitly.&nbsp; To ensure unambiguity in
URL processing, the language for these boolean operators is expressed
as <span style="font-weight: bold;">Prefix Notation</span>, and the
operators are <span style="font-weight: bold;">binary</span> only,
meaning that each one takes exactly two operands.<br>
<br>
You are probably more familiar with <span style="font-weight: bold;">Infix
Notation</span>, in which the operator is placed <span
        style="font-style: italic;">between</span> the operands - in Prefix
Notation, the operand is placed <span style="font-style: italic;">before<span
        style="font-style: italic;"><span style="font-style: italic;"><span
        style="font-style: italic;"> </span></span></span></span>its operands.<br>
<br>
&nbsp;&nbsp;&nbsp; INFIX:<span style="font-weight: bold;">&nbsp; <span
        style="font-style: italic;">x AND y<br>
&nbsp;&nbsp;&nbsp; </span></span><span style="font-style: italic;"></span>PREFIX:<span
        style="font-weight: bold;">&nbsp; <span style="font-style: italic;">AND
x y</span></span><span style="font-style: italic;"><br>
<span style="font-style: italic;"><span style="font-style: italic;"><br>
<span style="font-style: italic;"></span></span></span></span>The main
reason for using the Prefix Notation is that it removes any chance of
ambiguity in the operators that would need to be resolved with
parentheses.&nbsp; For Example:<br>
<br>
&nbsp;&nbsp;&nbsp; INFIX:&nbsp; <span style="font-style: italic;"><span
        style="font-weight: bold;">(x AND y) OR z</span></span><br>
&nbsp;&nbsp;&nbsp; PREFIX:&nbsp; <span style="font-style: italic;"><span
        style="font-weight: bold;">OR AND x y z<br>
</span></span><br>
&nbsp;&nbsp;&nbsp; INFIX:&nbsp; <span style="font-style: italic;"><span
        style="font-weight: bold;">x AND (y OR z)</span></span><br>
&nbsp;&nbsp;&nbsp; PREFIX:&nbsp; <span style="font-style: italic;"><span
        style="font-weight: bold;">AND x OR y z<br>
</span></span><span style="font-style: italic;"><span
        style="font-weight: bold;"><br>
</span></span>The two expressions in Infix Notation are only
distinguishable by their parentheses - if you take them away, it is not
clear which one you mean, whereas in the Prefix Notation, there is only
one way to interpret each of the expressions, with no parentheses
needed for grouping sub-expressions.<br>
<br>
In a URL, if you want to get all widgets in brand "bar" that have
property type of "foo" or "condo", you would say:<br>
<br>

<div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/-/AND/(urn:foo.widgets.brands)bar/OR/(urn:foo.widgets.type)foo</span><span
        style="font-family: monospace;">/(urn:foo.widgets.type)condo</span>
</div>
<span style="font-family: monospace;"></span><br>
There is, as discussed at the beginning of this section, an implicit <span
        style="font-weight: bold;">AND</span> at the top level.&nbsp; That
means that you can simplify this query to:<br>
<br>

<div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/-/(urn:foo.widgets.brands)bar/OR/(urn:foo.widgets.type)foo</span><span
        style="font-family: monospace;">/(urn:foo.widgets.type)condo</span>
</div>
<br>
If you want to do an AND or an OR of more than two things, you simply
chain the operators together, for example:<br>
<br>
&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;"><span
        style="font-style: italic;">x OR y OR z&nbsp; </span></span>in INFIX
becomes<span style="font-style: italic;"> </span><span
        style="font-weight: bold; font-style: italic;">OR x OR y z</span> in
PREFIX<br>
<br>
Or in a URL, if you want all "foo", "condo", and "house" widgets<br>
<span style="font-family: monospace;"></span><br>

<div id="codebox"><span style="font-family: monospace;">GET
/v1/widgets/acme/-/OR/(urn:foo.widgets.type)foo/OR/(urn:foo.widgets.type)condo</span><span
        style="font-family: monospace;">/(urn:foo.widgets.type)</span><span
        style="font-family: monospace;">house<br>
</span></div>
<br>
<br>
<span style="font-family: monospace;"></span><span
        style="font-family: monospace;"></span>
<hr style="width: 100%; height: 2px;">
<h2><a name="resources"></a>Additional resources</h2>
You may find the following third-party documents useful:<br>
<br>
&nbsp;&nbsp;&nbsp; * <a
        href="http://www-128.ibm.com/developerworks/xml/library/x-atom10.html">Overview
    of Atom</a> from IBM<br>
&nbsp;&nbsp;&nbsp; * <a
        href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">HTTP 1.1
    method definitions</a>; specification for GET, POST, PUT, and DELETE<br>
&nbsp;&nbsp;&nbsp; * <a
        href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP 1.1
    status code definitions</a><br>
&nbsp;&nbsp;&nbsp; * <a
        href="http://www.atomenabled.org/developers/syndication/">Atom
    Syndication Reference</a> (from Atom-enabled)<br>
&nbsp;&nbsp;&nbsp; * <a
        href="http://www-128.ibm.com/developerworks/library/x-atompp1/">Getting
    to know the Atom Publishing Protocol (from IBM)</a><span
        style="font-weight: bold;"><br>
&nbsp;&nbsp;&nbsp; * </span><a
        href="http://www.ibm.com/developerworks/xml/library/x-tipatom4.html">IBM
    Tip: Organize Documents with Atom Categories</a><br>
<br>
</div>
</body>
</html>
